home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-21 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  49KB  |  910 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: X Frame Parameters,  Next: Size And Position,  Prev: Initial Parameters,  Up: Frame Parameters
  20. X Window Frame Parameters
  21. -------------------------
  22.    Just what parameters a frame has depends on what display mechanism it
  23. uses.  Here is a table of the parameters of an X window frame:
  24. `name'
  25.      The name of the frame.
  26. `left'
  27.      The screen position of the left edge, in pixels.
  28. `top'
  29.      The screen position of the top edge, in pixels.
  30. `height'
  31.      The height of the frame contents, in pixels.
  32. `width'
  33.      The width of the frame contents, in pixels.
  34. `window-id'
  35.      The number of the X window for the frame.
  36. `minibuffer'
  37.      Whether this frame has its own minibuffer.  The value `t' means
  38.      yes, `nil' means no, `only' means this frame is just a minibuffer,
  39.      a minibuffer window (in some other frame) means the new frame uses
  40.      that minibuffer.
  41. `font'
  42.      The name of the font for text in the frame.  This is a string.
  43. `auto-raise'
  44.      Whether selecting the frame raises it (non-`nil' means yes).
  45. `auto-lower'
  46.      Whether deselecting the frame lowers it (non-`nil' means yes).
  47. `vertical-scroll-bars'
  48.      Whether the frame has a scroll bar for vertical scrolling
  49.      (non-`nil' means yes).
  50. `horizontal-scroll-bars'
  51.      Whether the frame has a scroll bar for horizontal scrolling
  52.      (non-`nil' means yes).  (Horizontal scroll bars are not currently
  53.      implemented.)
  54. `icon-type'
  55.      The type of icon to use for this frame when it is iconified.
  56.      Non-`nil' specifies a bitmap icon, `nil' a text icon.
  57. `foreground-color'
  58.      The color to use for the inside of a character.  We use strings to
  59.      designate colors; the X server defines the meaningful color names.
  60. `background-color'
  61.      The color to use for the background of text.
  62. `mouse-color'
  63.      The color for the mouse cursor.
  64. `cursor-color'
  65.      The color for the cursor that shows point.
  66. `border-color'
  67.      The color for the border of the frame.
  68. `cursor-type'
  69.      The way to display the cursor.  There are two legitimate values:
  70.      `bar' and `box'.  The value `bar' specifies a vertical bar between
  71.      characters as the cursor.  The value `box' specifies an ordinary
  72.      black box overlaying the character after point; that is the
  73.      default.
  74. `border-width'
  75.      The width in pixels of the window border.
  76. `internal-border-width'
  77.      The distance in pixels between text and border.
  78. `unsplittable'
  79.      If non-`nil', this frame's window is never split automatically.
  80. `visibility'
  81.      The state of visibility of the frame.  There are three
  82.      possibilities: `nil' for invisible, `t' for visible, and `icon' for
  83.      iconified.  *Note Visibility of Frames::.
  84. `menu-bar-lines'
  85.      The number of lines to allocate at the top of the frame for a menu
  86.      bar.  The default is zero.  *Note Menu Bar::.
  87. `parent-id'
  88.      The X Window number of the window that should be the parent of
  89.      this one.  Specifying this lets you create an Emacs window inside
  90.      some other application's window.  (It is not certain this will be
  91.      implemented; try it and see if it works.)
  92. File: elisp,  Node: Size And Position,  Prev: X Frame Parameters,  Up: Frame Parameters
  93. Frame Size And Position
  94. -----------------------
  95.    You can read or change the size and position of a frame using the
  96. frame parameters `left', `top', `height' and `width'.  When you create
  97. a frame, you must specify either both size parameters or neither.
  98. Likewise, you must specify either both position parameters or neither.
  99. Whatever geometry parameters you don't specify are chosen by the window
  100. manager in its usual fashion.
  101.    Here are some special features for working with sizes and positions:
  102.  - Function: set-frame-position FRAME LEFT TOP
  103.      This function sets the position of the top left corner of
  104.      FRAME--to LEFT and TOP.  These arguments are measured in pixels,
  105.      counting from the top left corner of the screen.
  106.  - Function: frame-height &optional FRAME
  107.  - Function: frame-width &optional FRAME
  108.      These functions return the height and width of FRAME, measured in
  109.      characters.  If you don't supply FRAME, they use the selected
  110.      frame.
  111.  - Function: frame-pixel-height &optional FRAME
  112.  - Function: frame-pixel-width &optional FRAME
  113.      These functions return the height and width of FRAME, measured in
  114.      pixels.  If you don't supply FRAME, they use the selected frame.
  115.  - Function: frame-char-height &optional FRAME
  116.  - Function: frame-char-width &optional FRAME
  117.      These functions return the height and width, respectively, of a
  118.      character in FRAME, measured in pixels.  The values depend on the
  119.      choice of font.  If you don't supply FRAME, these functions use
  120.      the selected frame.
  121.  - Function: set-frame-size FRAME COLS ROWS
  122.      This function sets the size of FRAME, measured in characters; COLS
  123.      and ROWS specify the new width and height.
  124.      To set the size with values measured in pixels, use
  125.      `modify-frame-parameters' to set the `width' and `height'
  126.      parameters.  *Note X Frame Parameters::.
  127.    The old-fashioned functions `set-screen-height' and
  128. `set-screen-width', which were used to specify the height and width of
  129. the screen in Emacs versions that did not support multiple frames, are
  130. still usable.  They apply to the selected frame.  *Note Screen Size::.
  131.  - Function: x-parse-geometry GEOM
  132.      The function `x-parse-geometry' converts a standard X windows
  133.      geometry string to an alist which you can use as part of the
  134.      argument to `x-create-frame'.
  135.      The alist describes which parameters were specified in GEOM, and
  136.      gives the values specified for them.  Each element looks like
  137.      `(PARAMETER . VALUE)'.  The possible PARAMETER values are `left',
  138.      `top', `width', and `height'.
  139.           (x-geometry "35x70+0-0")
  140.                => ((width . 35) (height . 70) (left . 0) (top . -1))
  141. File: elisp,  Node: Deleting Frames,  Next: Finding All Frames,  Prev: Frame Parameters,  Up: Frames
  142. Deleting Frames
  143. ===============
  144.    Frames remain potentially visible until you explicitly "delete"
  145. them.  A deleted frame cannot appear on the screen, but continues to
  146. exist as a Lisp object until there are no references to it.  There is no
  147. way to cancel the deletion of a frame aside from restoring a saved frame
  148. configuration (*note Frame Configurations::.); this is similar to the
  149. way windows behave.
  150.  - Command: delete-frame &optional FRAME
  151.      This function deletes the frame FRAME.  By default, FRAME is the
  152.      selected frame.
  153.  - Function: frame-live-p FRAME
  154.      The function `frame-live-p' returns non-`nil' if the frame FRAME
  155.      has not been deleted.
  156. File: elisp,  Node: Finding All Frames,  Next: Frames and Windows,  Prev: Deleting Frames,  Up: Frames
  157. Finding All Frames
  158. ==================
  159.  - Function: frame-list
  160.      The function `frame-list' returns a list of all the frames that
  161.      have not been deleted.  It is analogous to `buffer-list' for
  162.      buffers.  The list that you get is newly created, so modifying the
  163.      list doesn't have any effect on the internals of Emacs.
  164.  - Function: visible-frame-list
  165.      This function returns a list of just the currently visible frames.
  166.  - Function: next-frame &optional FRAME MINIBUF
  167.      The function `next-frame' lets you cycle conveniently through all
  168.      the frames from an arbitrary starting point.  It returns the "next"
  169.      frame after FRAME in the cycle.  If FRAME is omitted or `nil', it
  170.      defaults to the selected frame.
  171.      The second argument, MINIBUF, says which frames to consider:
  172.     `nil'
  173.           Exclude minibuffer-only frames.
  174.     a window
  175.           Consider only the frames using that particular window as their
  176.           minibuffer.
  177.     anything else
  178.           Consider all frames.
  179. File: elisp,  Node: Frames and Windows,  Next: Minibuffers and Frames,  Prev: Finding All Frames,  Up: Frames
  180. Frames and Windows
  181. ==================
  182.    All the non-minibuffer windows in a frame are arranged in a tree of
  183. subdivisions; the root of this tree is available via the function
  184. `frame-root-window'.  Each window is part of one and only one frame;
  185. you can get the frame with `window-frame'.
  186.  - Function: frame-root-window FRAME
  187.      This returns the root window of frame FRAME.
  188.  - Function: window-frame WINDOW
  189.      This function returns the frame that WINDOW is on.
  190.    At any time, exactly one window on any frame is "selected within the
  191. frame".  The significance of this designation is that selecting the
  192. frame also selects this window.  You can get the frame's current
  193. selected window with `frame-selected-window'.
  194.  - Function: frame-selected-window FRAME
  195.      This function returns the window on FRAME which is selected within
  196.      FRAME.
  197.    Conversely, selecting a window for Emacs with `select-window' also
  198. makes that window selected within its frame.  *Note Selecting Windows::.
  199. File: elisp,  Node: Minibuffers and Frames,  Next: Input Focus,  Prev: Frames and Windows,  Up: Frames
  200. Minibuffers and Frames
  201. ======================
  202.    Normally, each frame has its own minibuffer window at the bottom,
  203. which is used whenever that frame is selected.  If the frame has a
  204. minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
  205. Misc::.).
  206.    However, you can also create a frame with no minibuffer.  Such a
  207. frame must use the minibuffer window of some other frame.  When you
  208. create the frame, you can specify explicitly the frame on which to find
  209. the minibuffer to use.  If you don't, then the minibuffer is found in
  210. the frame which is the value of the variable
  211. `default-minibuffer-frame'.  Its value should be a frame which does
  212. have a minibuffer.
  213. File: elisp,  Node: Input Focus,  Next: Visibility of Frames,  Prev: Minibuffers and Frames,  Up: Frames
  214. Input Focus
  215. ===========
  216.    At any time, one frame in Emacs is the "selected frame".  The
  217. selected window always resides on the selected frame.
  218.  - Function: selected-frame
  219.      This function returns the selected frame.
  220.    The X server normally directs keyboard input to the X window that the
  221. mouse is in.  Some window managers use mouse clicks or keyboard events
  222. to "shift the focus" to various X windows, overriding the normal
  223. behavior of the server.
  224.    Lisp programs can switch frames "temporarily" by calling the
  225. function `select-frame'.  This does not override the window manager;
  226. rather, it escapes from the window manager's control until that control
  227. is somehow reasserted.
  228.  - Function: select-frame FRAME
  229.      This function selects frame FRAME, temporarily disregarding the X
  230.      Windows focus.  The selection of FRAME lasts until the next time
  231.      the user does something to select a different frame, or until the
  232.      next time this function is called.
  233.    Emacs cooperates with the X server and the window managers by
  234. arranging to select frames according to what the server and window
  235. manager ask for.  It does so by generating a special kind of input
  236. event, called a "focus" event.  The command loop handles a focus event
  237. by calling `internal-select-frame'.  *Note Focus Events::.
  238.  - Function: internal-select-frame FRAME
  239.      This function selects frame FRAME, assuming that the X server
  240.      focus already points to FRAME.
  241.      Focus events normally do their job by invoking this command.
  242.      Don't call it for any other reason.
  243. File: elisp,  Node: Visibility of Frames,  Next: Raising and Lowering,  Prev: Input Focus,  Up: Frames
  244. Visibility of Frames
  245. ====================
  246.    A frame may be "visible", "invisible", or "iconified".  If it is
  247. visible, you can see its contents.  If it is iconified, the frame's
  248. contents do not appear on the screen, but an icon does.  If the frame
  249. is invisible, it doesn't show in the screen, not even as an icon.
  250.  - Command: make-frame-visible &optional FRAME
  251.      This function makes frame FRAME visible.  If you omit FRAME, it
  252.      makes the selected frame visible.
  253.  - Command: make-frame-invisible &optional FRAME
  254.      This function makes frame FRAME invisible.  If you omit FRAME, it
  255.      makes the selected frame invisible.
  256.  - Command: iconify-frame &optional FRAME
  257.      This function iconifies frame FRAME.  If you omit FRAME, it
  258.      iconifies the selected frame.
  259.  - Function: frame-visible-p FRAME
  260.      This returns the visibility status of frame FRAME.  The value is
  261.      `t' if FRAME is visible, `nil' if it is invisible, and `icon' if
  262.      it is iconified.
  263.    The visibility status of a frame is also available as a frame
  264. parameter.  You can read or change it as such.  *Note X Frame
  265. Parameters::.
  266. File: elisp,  Node: Raising and Lowering,  Next: Frame Configurations,  Prev: Visibility of Frames,  Up: Frames
  267. Raising and Lowering Frames
  268. ===========================
  269.    The X window system uses a desktop metaphor.  Part of this metaphor
  270. is the idea that windows are stacked in a notional third dimension
  271. perpendicular to the screen surface, and thus ordered from "highest" to
  272. "lowest".  Where two windows overlap, the one higher up covers the one
  273. underneath.  Even a window at the bottom of the stack can be seen if no
  274. other window overlaps it.
  275.    A window's place in this ordering is not fixed; in fact, users tend
  276. to change the order frequently.  "Raising" a window means moving it
  277. "up", to the top of the stack.  "Lowering" a window means moving it to
  278. the bottom of the stack.  This motion is in the notional third
  279. dimension only, and does not change the position of the window on the
  280. screen.
  281.    You can raise and lower Emacs's X windows with these functions:
  282.  - Function: raise-frame FRAME
  283.      This function raises frame FRAME.
  284.  - Function: lower-frame FRAME
  285.      This function lowers frame FRAME.
  286.    You can also specify auto-raise (raising automatically when a frame
  287. is selected) or auto-lower (lowering automatically when it is
  288. deselected) for any frame using frame parameters.  *Note X Frame
  289. Parameters::.
  290. File: elisp,  Node: Frame Configurations,  Next: Mouse Tracking,  Prev: Raising and Lowering,  Up: Frames
  291. Frame Configurations
  292. ====================
  293.  - Function: current-frame-configuration
  294.      This function returns a "frame configuration" list which describes
  295.      the current arrangement of frames, all their properties, and the
  296.      window configuration of each one.
  297.  - Function: set-frame-configuration CONFIGURATION
  298.      This function restores the state of frames described in
  299.      CONFIGURATION.
  300. File: elisp,  Node: Mouse Tracking,  Next: Mouse Position,  Prev: Frame Configurations,  Up: Frames
  301. Mouse Tracking
  302. ==============
  303.    Sometimes it is useful to "track" the mouse, which means, to display
  304. something to indicate where the mouse is and move the indicator as the
  305. mouse moves.  For efficient mouse tracking, you need a way to wait until
  306. the mouse actually moves.
  307.    The convenient way to track the mouse is to ask for events to
  308. represent mouse motion.  Then you can wait for motion by waiting for an
  309. event.  In addition, you can easily handle any other sorts of events
  310. that may occur.  That is useful, because normally you don't want to
  311. track the mouse forever--only until some other event, such as the
  312. release of a button.
  313.  - Special Form: track-mouse BODY...
  314.      Execute BODY, meanwhile generating input events for mouse motion.
  315.      The code in BODY can read these events with `read-event' or
  316.      `read-key-sequence'.  *Note Motion Events::, for the format of
  317.      mouse motion events.
  318.      The value of `track-mouse' is that of the last form in BODY.
  319.    The usual purpose of tracking mouse motion is to indicate on the
  320. screen the consequences of pushing or releasing a button at the current
  321. position.
  322. File: elisp,  Node: Mouse Position,  Next: Pop-Up Menus,  Prev: Mouse Tracking,  Up: Frames
  323. Mouse Position
  324. ==============
  325.    The new functions `mouse-position' and `set-mouse-position' give
  326. access to the current position of the mouse.
  327.  - Function: mouse-position
  328.      This function returns a description of the position of the mouse.
  329.      The value looks like `(FRAME X . Y)', where X and Y are integers
  330.      giving the position in pixels relative to the top left corner of
  331.      the inside of FRAME.
  332.  - Function: set-mouse-position FRAME X Y
  333.      Thus function "warps the mouse" to position X, Y in frame FRAME.
  334.      The arguments X and Y are integers, giving the position in pixels
  335.      relative to the top left corner of the inside of FRAME.
  336.      Warping the mouse means changing the screen position of the mouse
  337.      as if the user had moved the physical mouse--thus simulating the
  338.      effect of actual mouse motion.
  339. File: elisp,  Node: Pop-Up Menus,  Next: X Selections,  Prev: Mouse Position,  Up: Frames
  340. Pop-Up Menus
  341. ============
  342.  - Function: x-popup-menu POSITION MENU
  343.      This function displays a pop-up menu and returns an indication of
  344.      what selection the user makes.
  345.      The argument POSITION specifies where on the screen to put the
  346.      menu.  It can be either a mouse button event (which says to put
  347.      the menu where the user actuated the button) or a list of this
  348.      form:
  349.           ((XOFFSET YOFFSET) WINDOW)
  350.      where XOFFSET and YOFFSET are positions measured in characters,
  351.      counting from the top left corner of WINDOW's frame.
  352.      The argument MENU says what to display in the menu.  It can be a
  353.      keymap or a list of keymaps (*note Menu Keymaps::.).
  354.      Alternatively, it can have the following form:
  355.           (TITLE PANE1 PANE2...)
  356.      where each pane is a list of form
  357.           (TITLE (LINE ITEM)...)
  358.      Each LINE should be a string, and each ITEM should be the value to
  359.      return if that LINE is chosen.
  360. File: elisp,  Node: X Selections,  Next: X Server,  Prev: Pop-Up Menus,  Up: Frames
  361. X Selections
  362. ============
  363.    The X server records a set of "selections" which permit transfer of
  364. data between application programs.  The various selections are
  365. distinguished by "selection types", represented in Emacs by symbols.  X
  366. clients including Emacs can read or set the selection for any given
  367. type.
  368.  - Function: x-set-selection TYPE DATA
  369.      This function sets a "selection" in the X server.  It takes two
  370.      arguments: a selection type TYPE, and the value to assign to it,
  371.      DATA.  If DATA is `nil', it means to clear out the selection.
  372.      Otherwise, DATA may be a string, a symbol, an integer (or a cons
  373.      of two integers or list of two integers), or a cons of two markers
  374.      pointing to the same buffer.  In the last case, the selection is
  375.      considered to be the text between the markers.  The data may also
  376.      be a vector of valid non-vector selection values.
  377.      Each possible TYPE has its own selection value, which changes
  378.      independently.  The usual values of TYPE are `PRIMARY' and
  379.      `SECONDARY'; these are symbols with upper-case names, in accord
  380.      with X Windows conventions.  The default is `PRIMARY'.
  381.  - Function: x-get-selection TYPE DATA-TYPE
  382.      This function accesses selections set up by Emacs or by other X
  383.      clients.  It takes two optional arguments, TYPE and DATA-TYPE.
  384.      The default for TYPE, the selection type, is `PRIMARY'.
  385.      The DATA-TYPE argument specifies the form of data conversion to
  386.      use, to convert the raw data obtained from another X client into
  387.      Lisp data.  Meaningful values include `TEXT', `STRING', `TARGETS',
  388.      `LENGTH', `DELETE', `FILE_NAME', `CHARACTER_POSITION',
  389.      `LINE_NUMBER', `COLUMN_NUMBER', `OWNER_OS', `HOST_NAME', `USER',
  390.      `CLASS', `NAME', `ATOM', and `INTEGER'.  (These are symbols with
  391.      upper-case names in accord with X conventions.)  The default for
  392.      DATA-TYPE is `STRING'.
  393.    The X server also has a set of numbered "cut buffers" which can
  394. store text or other data being moved between applications.  Cut buffers
  395. are considered obsolete, but Emacs supports them for the sake of X
  396. clients that still use them.
  397.  - Function: x-get-cut-buffer N
  398.      This function returns the contents of cut buffer number N.
  399.  - Function: x-set-cut-buffer STRING
  400.      This function stores STRING into the first cut buffer (cut buffer
  401.      0), moving the other values down through the series of cut buffers,
  402.      kill-ring-style.
  403. File: elisp,  Node: X Server,  Prev: X Selections,  Up: Frames
  404. X Server
  405. ========
  406.    This section describes how to access and change the overall status of
  407. the X server Emacs is using.
  408. * Menu:
  409. * X Connections::    Opening and closing the X server connection.
  410. * Resources::        Getting resource values from the server.
  411. * Rebinding X Keys::    Telling the server what input to send
  412.               for each keyboard key.
  413. * Server Data::        Getting info about the X server.
  414. File: elisp,  Node: X Connections,  Next: Resources,  Up: X Server
  415. X Connections
  416. -------------
  417.    You can close the connection with the X server with the function
  418. `x-close-current-connection', and open a new one with
  419. `x-open-connection' (perhaps with a different server and display).
  420.  - Function: x-close-current-connection
  421.      This function closes the connection to the X server.  It deletes
  422.      all frames, making Emacs effectively inaccessible to the user;
  423.      therefore, a Lisp program that closes the connection should open
  424.      another one.
  425.  - Function: x-open-connection DISPLAY &optional RESOURCE-STRING
  426.      This function opens a connection to an X server, for use of display
  427.      DISPLAY.
  428.      The optional argument RESOURCE-STRING is a string of resource
  429.      names and values, in the same format used in the `.Xresources'
  430.      file.  The values you specify override the resource values
  431.      recorded in the X server itself.  Here's an example of what this
  432.      string might look like:
  433.           "*BorderWidth: 3\n*InternalBorder: 2\n"
  434.  - Function: x-color-display-p
  435.      This returns `t' if the connected X display has color, and `nil'
  436.      otherwise.
  437.  - Function: x-color-defined-p COLOR
  438.      This function reports whether a color name is meaningful and
  439.      supported on the X display Emacs is using.  It returns `t' if the
  440.      display supports that color; otherwise, `nil'.
  441.      Black-and-white displays support just two colors, `"black"' or
  442.      `"white"'.  Color displays support many other colors.
  443.  - Function: x-synchronize FLAG
  444.      The function `x-synchronize' enables or disables synchronous
  445.      communication with the X server.  It enables synchronous
  446.      communication if FLAG is non-`nil', and disables it if FLAG is
  447.      `nil'.
  448.      In synchronous mode, Emacs waits for a response to each X protocol
  449.      command before doing anything else.  This is useful for debugging
  450.      Emacs, because protocol errors are reported right away, which
  451.      helps you find the erroneous command.  Synchronous mode is not the
  452.      default because it is much slower.
  453. File: elisp,  Node: Resources,  Next: Rebinding X Keys,  Prev: X Connections,  Up: X Server
  454. Resources
  455. ---------
  456.  - Function: x-get-resource ATTRIBUTE &optional NAME CLASS
  457.      The function `x-get-resource' retrieves a resource value from the X
  458.      Windows defaults database.
  459.      Resources are indexed by a combination of a "key" and a "class".
  460.      This function searches using a key of the form
  461.      `INSTANCE.ATTRIBUTE', where INSTANCE is the name under which Emacs
  462.      was invoked, and uses `Emacs' as the class.
  463.      The optional arguments COMPONENT and SUBCLASS add to the key and
  464.      the class, respectively.  You must specify both of them or neither.
  465.      If you specify them, the key is `INSTANCE.COMPONENT.ATTRIBUTE',
  466.      and the class is `Emacs.SUBCLASS'.
  467. File: elisp,  Node: Rebinding X Keys,  Next: Server Data,  Prev: Resources,  Up: X Server
  468. Rebinding X Server Keys
  469. -----------------------
  470.    The X server allows each client to specify what sequence of
  471. characters each keyboard key should generate, depending on the set of
  472. shift keys held down.  Emacs has functions to redefine these sequences
  473. in the X server.  Redefinitions via `x-rebind-key' apply only to Emacs.
  474. Other clients using the same X server are not affected.
  475.  - Function: x-rebind-key KEYSYM MODIFIERS NEWSTRING
  476.      This function redefines a keyboard key in the X server.  KEYSYM is
  477.      a string which conforms to the X keysym definitions found in
  478.      `X11/keysymdef.h', but without the prefix `XK_'.  MODIFIERS is
  479.      either `nil', meaning no modifier keys, or a list of names of
  480.      modifier keys, again using the names from `X11/keysymdef.h' but
  481.      without the `XK_' prefix.
  482.      The third argument, NEWSTRING, is the new definition of the key.
  483.      It is the sequence of characters that the key should produce as
  484.      input.
  485.      For example,
  486.           (x-rebind-key "F1" nil "abc")
  487.      causes the F1 function key to generate the string `"abc"'.
  488.      Similarly,
  489.           (x-rebind-key "BackSpace"
  490.                         (list "Shift" "Control_L" "c-s-BackSpace")
  491.      makes the BS key send the string `"c-s-BackSpace"' if either the
  492.      shift key or the left-hand control key is held down.
  493.  - Function: x-rebind-keys KEYSYM STRINGS
  494.      This function redefines the complete meaning of a single keyboard
  495.      key, specifying the behavior for each of the 16 shift masks
  496.      independently.
  497.      The argument KEYSYM specifies the key to rebind, as in
  498.      `x-rebind-key'.
  499.      The argument STRINGS is a list of 16 elements, one for each
  500.      possible shift mask value; the Nth element says how to redefine
  501.      the key KEYCODE with shift mask value N.  If element N is a
  502.      string, it is the new definition for shift mask N.  If element N
  503.      is `nil', the definition for shift mask N is unchanged.
  504. File: elisp,  Node: Server Data,  Prev: Rebinding X Keys,  Up: X Server
  505. Data about the X Server
  506. -----------------------
  507.    This section describes functions and a variable that you can use to
  508. get information about the capabilities and origin of the X server that
  509. Emacs is displaying its frames on.
  510.  - Function: x-display-screens
  511.      This function returns the number of screens associated with the
  512.      current display.
  513.  - Function: x-server-version
  514.      This function returns the list of version numbers of the X server
  515.      in use.
  516.  - Function: x-server-vendor
  517.      This function returns the vendor supporting the X server in use.
  518.  - Function: x-display-pixel-height
  519.      This function returns the height of this X screen in pixels.
  520.  - Function: x-display-mm-height
  521.      This function returns the height of this X screen in millimeters.
  522.  - Function: x-display-pixel-width
  523.      This function returns the width of this X screen in pixels.
  524.  - Function: x-display-mm-width
  525.      This function returns the width of this X screen in millimeters.
  526.  - Function: x-display-backing-store
  527.      This function returns the backing store capability of this screen.
  528.      Values can be the symbols `always', `when-mapped', or `not-useful'.
  529.  - Function: x-display-save-under
  530.      This function returns non-`nil' if this X screen supports the
  531.      SaveUnder feature.
  532.  - Function: x-display-planes
  533.      This function returns the number of planes this display supports.
  534.  - Function: x-display-visual-class
  535.      This function returns the visual class for this X screen.  The
  536.      value is one of the symbols `static-gray', `gray-scale',
  537.      `static-color', `pseudo-color', `true-color', and `direct-color'.
  538.  - Function: x-display-color-p
  539.      This function returns `t' if the X screen in use is a color screen.
  540.  - Function: x-display-color-cells
  541.      This function returns the number of color cells this X screen
  542.      supports.
  543.  - Variable: x-no-window-manager
  544.      This variable's value is is `t' if no X window manager is in use.
  545. File: elisp,  Node: Positions,  Next: Markers,  Prev: Frames,  Up: Top
  546. Positions
  547. *********
  548.    A "position" is the index of a character in the text of buffer.
  549. More precisely, a position identifies the place between two characters
  550. (or before the first character, or after the last character), so we can
  551. speak of the character before or after a given position.  However, the
  552. character after a position is often said to be "at" that position.
  553.    Positions are usually represented as integers starting from 1, but
  554. can also be represented as "markers"--special objects which relocate
  555. automatically when text is inserted or deleted so they stay with the
  556. surrounding characters.  *Note Markers::.
  557. * Menu:
  558. * Point::         The special position where editing takes place.
  559. * Motion::        Changing point.
  560. * Excursions::    Temporary motion and buffer changes.
  561. * Narrowing::     Restricting editing to a portion of the buffer.
  562. File: elisp,  Node: Point,  Next: Motion,  Prev: Positions,  Up: Positions
  563. Point
  564. =====
  565.    "Point" is a special buffer position used by many editing commands,
  566. including the self-inserting typed characters and text insertion
  567. functions.  Other commands move point through the text to allow editing
  568. and insertion at different places.
  569.    Like other positions, point designates a place between two characters
  570. (or before the first character, or after the last character), rather
  571. than a particular character.  Many terminals display the cursor over the
  572. character that immediately follows point; on such terminals, point is
  573. actually before the character on which the cursor sits.
  574.    The value of point is a number between 1 and the buffer size plus 1.
  575. If narrowing is in effect (*note Narrowing::.), then point is
  576. constrained to fall within the accessible portion of the buffer
  577. (possibly at one end of it).
  578.    Each buffer has its own value of point, which is independent of the
  579. value of point in other buffers.  Each window also has a value of point,
  580. which is independent of the value of point in other windows on the same
  581. buffer.  This is why point can have different values in various windows
  582. that display the same buffer.  When a buffer appears in only one window,
  583. the buffer's point and the window's point normally have the same value,
  584. so the distinction is rarely important.  *Note Window Point::, for more
  585. details.
  586.  - Function: point
  587.      This function returns the position of point in the current buffer,
  588.      as an integer.
  589.           (point)
  590.                => 175
  591.  - Function: point-min
  592.      This function returns the minimum accessible value of point in the
  593.      current buffer.  This is 1, unless narrowing is in effect, in
  594.      which case it is the position of the start of the region that you
  595.      narrowed to.  (*Note Narrowing::.)
  596.  - Function: point-max
  597.      This function returns the maximum accessible value of point in the
  598.      current buffer.  This is `(1+ (buffer-size))', unless narrowing is
  599.      in effect, in which case it is the position of the end of the
  600.      region that you narrowed to.  (*Note Narrowing::).
  601.  - Function: buffer-end FLAG
  602.      This function returns `(point-min)' if FLAG is less than 1,
  603.      `(point-max)' otherwise.  The argument FLAG must be a number.
  604.  - Function: buffer-size
  605.      This function returns the total number of characters in the current
  606.      buffer.  In the absence of any narrowing (*note Narrowing::.),
  607.      `point-max' returns a value one larger than this.
  608.           (buffer-size)
  609.                => 35
  610.           (point-max)
  611.                => 36
  612.  - Variable: buffer-saved-size
  613.      The value of this buffer-local variable is the former length of the
  614.      current buffer, as of the last time it was read in, saved or
  615.      auto-saved.
  616. File: elisp,  Node: Motion,  Next: Excursions,  Prev: Point,  Up: Positions
  617. Motion
  618. ======
  619.    Motion functions change the value of point, either relative to the
  620. current value of point, relative to the beginning or end of the buffer,
  621. or relative to the edges of the selected window.  *Note Point::.
  622. * Menu:
  623. * Character Motion::       Moving in terms of characters.
  624. * Word Motion::            Moving in terms of words.
  625. * Buffer End Motion::      Moving to the beginning or end of the buffer.
  626. * Text Lines::             Moving in terms of lines of text.
  627. * Screen Lines::           Moving in terms of lines as displayed.
  628. * Vertical Motion::        Implementation of `next-line' and
  629.                              `previous-line'.
  630. * List Motion::            Moving by parsing lists and sexps.
  631. * Skipping Characters::    Skipping characters belonging to a certain set.
  632. File: elisp,  Node: Character Motion,  Next: Word Motion,  Prev: Motion,  Up: Motion
  633. Motion by Characters
  634. --------------------
  635.    These functions move point based on a count of characters.
  636. `goto-char' is a fundamental primitive because it is the way to move
  637. point to a specified position.
  638.  - Command: goto-char POSITION
  639.      This function sets point in the current buffer to the value
  640.      POSITION.  If POSITION is less than 1, then point is set to the
  641.      beginning of the buffer.  If it is greater than the length of the
  642.      buffer, then point is set to the end of the buffer.
  643.      If narrowing is in effect, then the position is still measured
  644.      from the beginning of the buffer, but point cannot be moved
  645.      outside of the accessible portion.  Therefore, if POSITION is too
  646.      small, point is set to the beginning of the accessible portion of
  647.      the text; if POSITION is too large, point is set to the end.
  648.      When this function is called interactively, POSITION is the
  649.      numeric prefix argument, if provided; otherwise it is read from the
  650.      minibuffer.
  651.      `goto-char' returns POSITION.
  652.  - Command: forward-char &optional COUNT
  653.      This function moves point forward, towards the end of the buffer,
  654.      COUNT characters (or backward, towards the beginning of the
  655.      buffer, if COUNT is negative).  If the function attempts to move
  656.      point past the beginning or end of the buffer (or the limits of the
  657.      accessible portion, when narrowing is in effect), an error is
  658.      signaled with error code `beginning-of-buffer' or `end-of-buffer'.
  659.      In an interactive call, COUNT is the numeric prefix argument.
  660.  - Command: backward-char &optional COUNT
  661.      This function moves point backward, towards the beginning of the
  662.      buffer, COUNT characters (or forward, towards the end of the
  663.      buffer, if COUNT is negative).  If the function attempts to move
  664.      point past the beginning or end of the buffer (or the limits of
  665.      the accessible portion, when narrowing is in effect), an error is
  666.      signaled with error code `beginning-of-buffer' or `end-of-buffer'.
  667.      In an interactive call, COUNT is the numeric prefix argument.
  668. File: elisp,  Node: Word Motion,  Next: Buffer End Motion,  Prev: Character Motion,  Up: Motion
  669. Motion by Words
  670. ---------------
  671.    These functions for parsing words use the syntax table to decide
  672. whether a given character is part of a word.  *Note Syntax Tables::.
  673.  - Command: forward-word COUNT
  674.      This function moves point forward COUNT words (or backward if
  675.      COUNT is negative).  Normally it returns `t'.  If this motion
  676.      encounters the beginning or end of the buffer, or the limits of the
  677.      accessible portion when narrowing is in effect, point stops there
  678.      and the value is `nil'.
  679.      In an interactive call, COUNT is set to the numeric prefix
  680.      argument.
  681.  - Command: backward-word COUNT
  682.      This function just like `forward-word', except that it moves
  683.      backward until encountering the front of a word, rather than
  684.      forward.
  685.      In an interactive call, COUNT is set to the numeric prefix
  686.      argument.
  687.      This function is rarely used in programs, as it is more efficient
  688.      to call `forward-word' with negative argument.
  689.  - Variable: words-include-escapes
  690.      This variable affects the behavior of `forward-word' and everything
  691.      that uses it.  If it is non-`nil', then characters in the "escape"
  692.      and "character quote" syntax classes count as part of words.
  693.      Otherwise, they do not.
  694. File: elisp,  Node: Buffer End Motion,  Next: Text Lines,  Prev: Word Motion,  Up: Motion
  695. Motion to an End of the Buffer
  696. ------------------------------
  697.    To move point to the beginning of the buffer, write:
  698.      (goto-char (point-min))
  699. Likewise, to move to the end of the buffer, use:
  700.      (goto-char (point-max))
  701.    Here are two commands which users use to do these things.  They are
  702. documented here to warn you not to use them in Lisp programs, because
  703. they set the mark and display messages in the echo area.
  704.  - Command: beginning-of-buffer &optional N
  705.      This function moves point to the beginning of the buffer (or the
  706.      limits of the accessible portion, when narrowing is in effect),
  707.      setting the mark at the previous position.  If N is non-`nil',
  708.      then it puts point N tenths of the way from the beginning of the
  709.      buffer.
  710.      In an interactive call, N is the numeric prefix argument, if
  711.      provided; otherwise N defaults to `nil'.
  712.      Don't use this function in Lisp programs!
  713.  - Command: end-of-buffer &optional N
  714.      This function moves point to the end of the buffer (or the limits
  715.      of the accessible portion, when narrowing is in effect), setting
  716.      the mark at the previous position.  If N is non-`nil', then it puts
  717.      point N tenths of the way from the end.
  718.      In an interactive call, N is the numeric prefix argument, if
  719.      provided; otherwise N defaults to `nil'.
  720.      Don't use this function in Lisp programs!
  721. File: elisp,  Node: Text Lines,  Next: Screen Lines,  Prev: Buffer End Motion,  Up: Motion
  722. Motion by Text Lines
  723. --------------------
  724.    Text lines are portions of the buffer delimited by newline
  725. characters, which are regarded as part of the previous line.  The first
  726. text line begins at the beginning of the buffer, and the last text line
  727. ends at the end of the buffer whether or not the last character is a
  728. newline.  The division of the buffer into text lines is not affected by
  729. the width of the window, or by how tabs and control characters are
  730. displayed.
  731.  - Command: goto-line LINE
  732.      This function moves point to the front of the LINEth line,
  733.      counting from line 1 at beginning of buffer.  If LINE is less than
  734.      1, then point is set to the beginning of the buffer.  If LINE is
  735.      greater than the number of lines in the buffer, then point is set
  736.      to the *end of the last line* of the buffer.
  737.      If narrowing is in effect, then LINE still counts from the
  738.      beginning of the buffer, but point cannot go outside the accessible
  739.      portion.  So point is set at the beginning or end of the accessible
  740.      portion of the text if the line number specifies a position that is
  741.      inaccessible.
  742.      The return value of `goto-line' is the difference between LINE and
  743.      the line number of the line to which point actually was able move
  744.      (before taking account of any narrowing).  Thus, the value is
  745.      positive if the scan encounters the end of the buffer.
  746.      In an interactive call, LINE is the numeric prefix argument if one
  747.      has been provided.  Otherwise LINE is read in the minibuffer.
  748.  - Command: beginning-of-line &optional COUNT
  749.      This function moves point to the beginning of the current line.
  750.      With an argument COUNT not `nil' or 1, it moves forward COUNT-1
  751.      lines and then to the beginning of the line.
  752.      If this function reaches the end of the buffer (or of the
  753.      accessible portion, if narrowing is in effect), it positions point
  754.      at the beginning of the last line.  No error is signaled.
  755.  - Command: end-of-line &optional COUNT
  756.      This function moves point to the end of the current line.  With an
  757.      argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
  758.      then to the end of the line.
  759.      If this function reaches the end of the buffer (or of the
  760.      accessible portion, if narrowing is in effect), it positions point
  761.      at the end of the last line.  No error is signaled.
  762.  - Command: forward-line &optional COUNT
  763.      This function moves point forward COUNT lines, to the beginning of
  764.      the line.  If COUNT is negative, it moves point -COUNT lines
  765.      backward, to the beginning of the line.
  766.      If the beginning or end of the buffer (or of the accessible
  767.      portion) is encountered before that many lines are found, then
  768.      point stops at the beginning or end.  No error is signaled.
  769.      `forward-line' returns the difference between COUNT and the number
  770.      of lines actually moved.  If you attempt to move down five lines
  771.      from the beginning of a buffer that has only three lines, point
  772.      will positioned at the end of the last line, and the value will be
  773.      2.
  774.      In an interactive call, COUNT is the numeric prefix argument.
  775.  - Function: count-lines START END
  776.      This function returns the number of lines between the positions
  777.      START and END in the current buffer.  If START and END are equal,
  778.      then it returns 0.  Otherwise it returns at least 1, even if START
  779.      and END are on the same line.  This is because the text between
  780.      them, considered in isolation, must contain at least one line
  781.      unless it is empty.
  782.      Here is an example of using `count-lines':
  783.           (defun current-line ()
  784.             "Return the vertical position of point
  785.           in the selected window.  Top line is 0.
  786.           Counts each text line only once, even if it wraps."
  787.             (+ (count-lines (window-start) (point))
  788.                (if (= (current-column) 0) 1 0)
  789.                -1))
  790.    Also see the functions `bolp' and `eolp' in *Note Near Point::.
  791. These functions do not move point, but test whether it is already at the
  792. beginning or end of a line.
  793. File: elisp,  Node: Screen Lines,  Next: Vertical Motion,  Prev: Text Lines,  Up: Motion
  794. Motion by Screen Lines
  795. ----------------------
  796.    The line functions in the previous section count text lines,
  797. delimited only by newline characters.  By contrast, these functions
  798. count screen lines, which are defined by the way the text appears on
  799. the screen.  A text line is a single screen line if it is short enough
  800. to fit the width of the selected window, but otherwise it may occupy
  801. several screen lines.
  802.    In some cases, text lines are truncated on the screen rather than
  803. continued onto additional screen lines.  Then `vertical-motion' moves
  804. point just like `forward-line'.  *Note Truncation::.
  805.    Because the width of a given string depends on the flags which
  806. control the appearance of certain characters, `vertical-motion' will
  807. behave differently on a given piece of text found in different buffers.
  808. It will even act differently in different windows showing the same
  809. buffer, because the width may differ and so may the truncation flag.
  810. *Note Usual Display::.
  811.  - Function: vertical-motion COUNT
  812.      This function moves point to the start of the screen line COUNT
  813.      screen lines down from the screen line containing point.  If COUNT
  814.      is negative, it moves up instead.
  815.      This function returns the number of lines moved.  The value may be
  816.      less in absolute value than COUNT if the beginning or end of the
  817.      buffer was reached.
  818.  - Command: move-to-window-line COUNT
  819.      This function moves point with respect to the text currently
  820.      displayed in the selected window.  Point is moved to the beginning
  821.      of the screen line COUNT screen lines from the top of the window.
  822.      If COUNT is negative, point moves either to the beginning of the
  823.      line -COUNT lines from the bottom or else to the last line of the
  824.      buffer if the buffer ends above the specified screen position.
  825.      If COUNT is `nil', then point moves to the beginning of the line
  826.      in the middle of the window.  If the absolute value of COUNT is
  827.      greater than the size of the window, then point moves to the place
  828.      which would appear on that screen line if the window were tall
  829.      enough.  This will probably cause the next redisplay to scroll to
  830.      bring that location onto the screen.
  831.      In an interactive call, COUNT is the numeric prefix argument.
  832.      The value returned is the window line number, with the top line in
  833.      the window numbered 0.
  834. File: elisp,  Node: Vertical Motion,  Next: List Motion,  Prev: Screen Lines,  Up: Motion
  835. The User-Level Vertical Motion Commands
  836. ---------------------------------------
  837.    A goal column is useful if you want to edit text such as a table in
  838. which you want to move point to a certain column on each line.  The goal
  839. column affects the vertical text line motion commands, `next-line' and
  840. `previous-line'.  *Note Basic Editing Commands: (emacs)Basic.
  841.  - User Option: goal-column
  842.      This variable holds an explicitly specified goal column for
  843.      vertical line motion commands.  If it is an integer, it specifies
  844.      a column, and these commands try to move to that column on each
  845.      line.  If it is `nil', then the commands set their own goal
  846.      columns.  Any other value is invalid.
  847.  - Variable: temporary-goal-column
  848.      This variable holds the temporary goal column during a sequence of
  849.      consecutive vertical line motion commands.  It is overridden by
  850.      `goal-column' if that is non-`nil'.  It is set each time a
  851.      vertical motion command is invoked, unless the previous command
  852.      was also a vertical motion command.
  853.  - User Option: track-eol
  854.      This variable controls how the vertical line motion commands
  855.      operate when starting at the end of a line.  If `track-eol' is
  856.      non-`nil', then vertical motion starting at the end of a line will
  857.      keep to the ends of lines.  This means moving to the end of each
  858.      line moved onto.  The value of `track-eol' has no effect if point
  859.      is not at the end of a line when the first vertical motion command
  860.      is given.
  861.      `track-eol' has its effect by causing `temporary-goal-column' to
  862.      be set to 9999 instead of to the current column.
  863.  - Command: set-goal-column UNSET
  864.      This command sets the variable `goal-column' to specify a permanent
  865.      goal column for the vertical line motion commands.  If UNSET is
  866.      `nil', then `goal-column' is set to the current column of point.
  867.      If UNSET is non-`nil', then `goal-column' is set to `nil'.
  868.      This function is intended for interactive use; and in an
  869.      interactive call, UNSET is the raw prefix argument.
  870. File: elisp,  Node: List Motion,  Next: Skipping Characters,  Prev: Vertical Motion,  Up: Motion
  871. Moving over Balanced Expressions
  872. --------------------------------
  873.    Here are several functions concerned with balanced-parenthesis
  874. expressions (also called "sexps" in connection with moving across them
  875. in Emacs).  The syntax table controls how these functions interpret
  876. various characters; see *Note Syntax Tables::.  *Note Parsing
  877. Expressions::, for lower-level primitives for scanning sexps or parts of
  878. sexps.  For user-level commands, see *Note Lists and Sexps:
  879. (emacs)Lists and Sexps.
  880.  - Command: forward-list ARG
  881.      Move forward across ARG balanced groups of parentheses.  (Other
  882.      syntactic entities such as words or paired string quotes are
  883.      ignored.)
  884.  - Command: backward-list ARG
  885.      Move backward across ARG balanced groups of parentheses.  (Other
  886.      syntactic entities such as words or paired string quotes are
  887.      ignored.)
  888.  - Command: up-list ARG
  889.      Move forward out of ARG levels of parentheses.  A negative
  890.      argument means move backward but still to a less deep spot.
  891.  - Command: down-list ARG
  892.      Move forward down ARG levels of parentheses.  A negative argument
  893.      means move backward but still go down ARG level.
  894.  - Command: forward-sexp ARG
  895.      Move forward across ARG balanced expressions.  Balanced
  896.      expressions include both those delimited by parentheses and other
  897.      kinds, such as words and string constants.  For example,
  898.           ---------- Buffer: foo ----------
  899.           (concat-!- "foo " (car x) y z)
  900.           ---------- Buffer: foo ----------
  901.           
  902.           (forward-sexp 3)
  903.                => nil
  904.           
  905.           ---------- Buffer: foo ----------
  906.           (concat "foo " (car x) y-!- z)
  907.           ---------- Buffer: foo ----------
  908.  - Command: backward-sexp ARG
  909.      Move backward across ARG balanced expressions.
  910.